From 0a60e2963c1a3ec9746d7b9f06428d01ff11cece Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Wed, 5 Jan 2000 15:04:23 +0000 Subject: [PATCH] Missing , remove extra dos2unix missing Wed Jan 5 10:23:41 2000 Owen Taylor * gtk/tmpl/gtkprogress.sgml: Missing , remove extra * gtk/tmpl/gtkobject.sgml: dos2unix * gtk/tmpl/gtkcurve.sgml: missing * gtk/tmpl/gtkarg.sgml: dos2unix, missing * gtk/tmpl/gtkcolorsel.sgml: Missing 's * gtk/tmpl/gtksignal.sgml (signal): dos2unix, missing 's * gtk/tmpl/gtkmarshal.sgml: Missing --- docs/reference/ChangeLog | 10 + docs/reference/gtk/tmpl/gtkarg.sgml | 404 ++--- docs/reference/gtk/tmpl/gtkcolorsel.sgml | 3 + docs/reference/gtk/tmpl/gtkcurve.sgml | 2 +- docs/reference/gtk/tmpl/gtkmarshal.sgml | 1 + docs/reference/gtk/tmpl/gtkobject.sgml | 1833 +++++++++++----------- docs/reference/gtk/tmpl/gtkprogress.sgml | 4 + docs/reference/gtk/tmpl/gtksignal.sgml | 1056 ++++++------- 8 files changed, 1666 insertions(+), 1647 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index aae898456e..682384ba21 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,13 @@ +Wed Jan 5 10:23:41 2000 Owen Taylor + + * gtk/tmpl/gtkprogress.sgml: Missing , remove extra + * gtk/tmpl/gtkobject.sgml: dos2unix + * gtk/tmpl/gtkcurve.sgml: missing + * gtk/tmpl/gtkarg.sgml: dos2unix, missing + * gtk/tmpl/gtkcolorsel.sgml: Missing 's + * gtk/tmpl/gtksignal.sgml (signal): dos2unix, missing 's + * gtk/tmpl/gtkmarshal.sgml: Missing + 1999-11-16 Damon Chaplin * gtk/tmpl/gtkmenubar.sgml: fixed minor error - using . diff --git a/docs/reference/gtk/tmpl/gtkarg.sgml b/docs/reference/gtk/tmpl/gtkarg.sgml index fea078b9d8..8e97cc2e2f 100644 --- a/docs/reference/gtk/tmpl/gtkarg.sgml +++ b/docs/reference/gtk/tmpl/gtkarg.sgml @@ -1,202 +1,202 @@ - -Implementation of Object Properties - - -Utility function to manipulate lists of named, typed arguments. - - - -All the functions in here are marked a Non-public. -We describe it anyway because it is occasionally useful -to understand how the work is done. - - -Arguments are a way of describing a named parameter to a function. -They have two important roles within gtk+: - - - -they describe object properties. -This means that they present an interface to get and set a named-type -for any type of object in a consistent way. -(All the relevant functions to do this start with gtk_object_set -or gtk_object_get). - - - - -they describe signal arguments. -This is a lot less often needed but still useful. -Usually if you are just emitting or creating a particular signal -it is more convenient to just use gtk_signal_emit() or gtk_signal_new(). -However if you are writing a function to emit or create an arbitrary -signal, you must use gtk_signal_emitv() or gtk_signal_newv(). - - - - - - - -#GtkObject. - - - - -A structure containing information about the argument. -Returned by gtk_arg_get_info(). - - -@class_type: if the argument is an object, this is the object class type. -@name: the name of the argument. -@type: the type of the argument; it may be an object's type -or a fundamental type. -@arg_flags: flags applicable to the argument (i.e. readable, writable, -and whether it needs to be constructed). -@full_name: the object name and argument name separated by ::, -e.g. "GtkObject::user_data" or "GtkButton::label". -@arg_id: the unique argument identified. -@seq_id: ??? - - - -Creates a new argument of a certain type, set to 0 or NULL. - - -@arg_type: the type of the argument. -@Returns: the newly created #GtkArg. - - - - -It will either copy data into an existing argument or allocate a new argument -and copy the data. Strings are duplicated. All other pointers and -values are copied (shallowly-- that is the pointers themselves are -copied, not the data they point to.) - - -You should call gtk_arg_reset() on dest_arg before calling this -if the argument may contain string data that you want freed. - - -@src_arg: the argument to duplicate. -@dest_arg: the argument to copy over (or NULL to create a new #GtkArg). -@Returns: the new #GtkArg (or dest_arg, if it was not NULL). - - - - -Frees the argument, and optionally its contents. - - -@arg: the argument to free. -@free_contents: whether to free the string, if it is a string. - - - - -Private: given a hashtable of argument information it takes a vararg -list and parses it into arguments (in the form of lists of #GtkArgs -and lists of #GtkArgInfos. - - -The list of arguments starts with first_arg_name then the first argument's -value. Followed by any number of additional name/argument pairs, -terminated with NULL. - - -@object_type: the type of object we are collecting arguments for. -@arg_info_hash_table: a hashtable mapping from names of arguments -to their #GtkArgInfos. -@arg_list_p: a returned list of arguments obtained from parsing the -varargs. -@info_list_p: a returned list of the #GtkArgInfos. -@first_arg_name: the name of the first argument. -@var_args: a va_list containing the value of the first argument, -followed by name/value pairs, followed by NULL. -@Returns: an error message on failure, or NULL otherwise. - - - - -Private: erase lists of arguments returned from gtk_args_collect(). - - -@arg_list: arg_list_p returned from gtk_args_collect(). -@info_list: info_list_p returned from gtk_args_collect(). - - - - -Private: get information about an argument. - - -@object_type: the type of object. -@arg_info_hash_table: the hashtable of #GtkArgInfos. -@arg_name: the name of the argument to lookup. -@info_p: the argument info. -@Returns: an error message on failure, or NULL otherwise. - - - - -Create a new argument registered with a class. - - -@base_class_type: the basic type having the arguments, almost alway -GTK_TYPE_OBJECT, except if your defining a different type argument -that gets a different namespace. #GtkContainer does this to define -per-child arguments of the container. -@arg_name: name of the argument to create. (must be a static constant string) -@class_n_args_offset: offset into the base class structure that tells -the number of arguments. -@arg_info_hash_table: hashtable of #GtkArgInfos. -@arg_type: type of the argument. -@arg_flags: flags of the argument. -@arg_id: ??? -@Returns: the new #GtkArgInfo. - - - - -Private: from a class type and its arginfo hashtable, -get an array of #GtkArgs that this object accepts. - - -@class_type: the class type. -@arg_info_hash_table: the hashtable of #GtkArgInfos. -@arg_flags: returned array of argument flags. -@n_args_p: the number of arguments this object accepts. -@Returns: the array of arguments (or NULL on error). - - - - -Given a fully qualified argument name (e.g. "GtkButton::label") -it returns just the argument name (e.g. "label") unless -the argument name was invalid, in which case it returns NULL. - - -@arg_name: the fully-qualified argument name. -@Returns: the base argument name. - - - - -A #GCompareFunc for hashing #GtkArgInfos. - - -@arg_info_1: a #GtkArgInfo. -@arg_info_2: a #GtkArgInfo. -@Returns: whether the arguments are the same. - - - - -A #GHashFunc for hashing #GtkArgInfos. - - -@arg_info: a #GtkArgInfo. -@Returns: a hash value for that #GtkArgInfo. - - + +Implementation of Object Properties + + +Utility function to manipulate lists of named, typed arguments. + + + +All the functions in here are marked a Non-public. +We describe it anyway because it is occasionally useful +to understand how the work is done. + + +Arguments are a way of describing a named parameter to a function. +They have two important roles within gtk+: + + + +they describe object properties. +This means that they present an interface to get and set a named-type +for any type of object in a consistent way. +(All the relevant functions to do this start with gtk_object_set +or gtk_object_get). + + + + +they describe signal arguments. +This is a lot less often needed but still useful. +Usually if you are just emitting or creating a particular signal +it is more convenient to just use gtk_signal_emit() or gtk_signal_new(). +However if you are writing a function to emit or create an arbitrary +signal, you must use gtk_signal_emitv() or gtk_signal_newv(). + + + + + + + +#GtkObject. + + + + +A structure containing information about the argument. +Returned by gtk_arg_get_info(). + + +@class_type: if the argument is an object, this is the object class type. +@name: the name of the argument. +@type: the type of the argument; it may be an object's type +or a fundamental type. +@arg_flags: flags applicable to the argument (i.e. readable, writable, +and whether it needs to be constructed). +@full_name: the object name and argument name separated by ::, +e.g. "GtkObject::user_data" or "GtkButton::label". +@arg_id: the unique argument identified. +@seq_id: ??? + + + +Creates a new argument of a certain type, set to 0 or NULL. + + +@arg_type: the type of the argument. +@Returns: the newly created #GtkArg. + + + + +It will either copy data into an existing argument or allocate a new argument +and copy the data. Strings are duplicated. All other pointers and +values are copied (shallowly-- that is the pointers themselves are +copied, not the data they point to.) + + +You should call gtk_arg_reset() on dest_arg before calling this +if the argument may contain string data that you want freed. + + +@src_arg: the argument to duplicate. +@dest_arg: the argument to copy over (or NULL to create a new #GtkArg). +@Returns: the new #GtkArg (or dest_arg, if it was not NULL). + + + + +Frees the argument, and optionally its contents. + + +@arg: the argument to free. +@free_contents: whether to free the string, if it is a string. + + + + +Private: given a hashtable of argument information it takes a vararg +list and parses it into arguments (in the form of lists of #GtkArgs +and lists of #GtkArgInfos. + + +The list of arguments starts with first_arg_name then the first argument's +value. Followed by any number of additional name/argument pairs, +terminated with NULL. + + +@object_type: the type of object we are collecting arguments for. +@arg_info_hash_table: a hashtable mapping from names of arguments +to their #GtkArgInfos. +@arg_list_p: a returned list of arguments obtained from parsing the +varargs. +@info_list_p: a returned list of the #GtkArgInfos. +@first_arg_name: the name of the first argument. +@var_args: a va_list containing the value of the first argument, +followed by name/value pairs, followed by NULL. +@Returns: an error message on failure, or NULL otherwise. + + + + +Private: erase lists of arguments returned from gtk_args_collect(). + + +@arg_list: arg_list_p returned from gtk_args_collect(). +@info_list: info_list_p returned from gtk_args_collect(). + + + + +Private: get information about an argument. + + +@object_type: the type of object. +@arg_info_hash_table: the hashtable of #GtkArgInfos. +@arg_name: the name of the argument to lookup. +@info_p: the argument info. +@Returns: an error message on failure, or NULL otherwise. + + + + +Create a new argument registered with a class. + + +@base_class_type: the basic type having the arguments, almost alway +GTK_TYPE_OBJECT, except if your defining a different type argument +that gets a different namespace. #GtkContainer does this to define +per-child arguments of the container. +@arg_name: name of the argument to create. (must be a static constant string) +@class_n_args_offset: offset into the base class structure that tells +the number of arguments. +@arg_info_hash_table: hashtable of #GtkArgInfos. +@arg_type: type of the argument. +@arg_flags: flags of the argument. +@arg_id: ??? +@Returns: the new #GtkArgInfo. + + + + +Private: from a class type and its arginfo hashtable, +get an array of #GtkArgs that this object accepts. + + +@class_type: the class type. +@arg_info_hash_table: the hashtable of #GtkArgInfos. +@arg_flags: returned array of argument flags. +@n_args_p: the number of arguments this object accepts. +@Returns: the array of arguments (or NULL on error). + + + + +Given a fully qualified argument name (e.g. "GtkButton::label") +it returns just the argument name (e.g. "label") unless +the argument name was invalid, in which case it returns NULL. + + +@arg_name: the fully-qualified argument name. +@Returns: the base argument name. + + + + +A #GCompareFunc for hashing #GtkArgInfos. + + +@arg_info_1: a #GtkArgInfo. +@arg_info_2: a #GtkArgInfo. +@Returns: whether the arguments are the same. + + + + +A #GHashFunc for hashing #GtkArgInfos. + + +@arg_info: a #GtkArgInfo. +@Returns: a hash value for that #GtkArgInfo. + + diff --git a/docs/reference/gtk/tmpl/gtkcolorsel.sgml b/docs/reference/gtk/tmpl/gtkcolorsel.sgml index 6bda38f810..f3152384c1 100644 --- a/docs/reference/gtk/tmpl/gtkcolorsel.sgml +++ b/docs/reference/gtk/tmpl/gtkcolorsel.sgml @@ -43,17 +43,20 @@ The available policies are: %GTK_UPDATE_CONTINUOUS - signals are sent continuously as the color selection changes. + %GTK_UPDATE_DISCONTINUOUS - signals are sent only when the mouse button is released. + %GTK_UPDATE_DELAYED - signals are sent when the mouse button is released or when the mouse has been motionless for a period of time. + diff --git a/docs/reference/gtk/tmpl/gtkcurve.sgml b/docs/reference/gtk/tmpl/gtkcurve.sgml index a056d270d7..e8ada7ac68 100644 --- a/docs/reference/gtk/tmpl/gtkcurve.sgml +++ b/docs/reference/gtk/tmpl/gtkcurve.sgml @@ -23,7 +23,7 @@ draw the points of the curve freely, and they are not connected at all. #GtkGammaCurve -a subclass for editing gamma curves. +a subclass for editing gamma curves. diff --git a/docs/reference/gtk/tmpl/gtkmarshal.sgml b/docs/reference/gtk/tmpl/gtkmarshal.sgml index 92d29caf1b..9163b99bf8 100644 --- a/docs/reference/gtk/tmpl/gtkmarshal.sgml +++ b/docs/reference/gtk/tmpl/gtkmarshal.sgml @@ -67,6 +67,7 @@ void marshal_INT__POINTER_POINTER_INT_INT(GtkObject* object, } + diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml index 830deb3958..43a2acffad 100644 --- a/docs/reference/gtk/tmpl/gtkobject.sgml +++ b/docs/reference/gtk/tmpl/gtkobject.sgml @@ -1,917 +1,916 @@ - -GtkObject - - -The base class of the Gtk type hierarchy. - - - -Description - -GtkObject is the root of the gtk+ type hierarchy. It serves -a similar roles as java's Object class. It is used -by the type-casting system to represent the base composite type. - - -Objects have arguments that are -name/typed-value pairs. -They may be readable or writable (or both or neither). -The special handlers in every object are responsible for -setting and getting these parameters. -If the handler for a given argument must -be called before the object may be used, be sure the -#GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags -are set; otherwise they are set only when the user does so. - - -Object also store a simpler association table, sometimes -called the object_data. This is just an efficient mapping from -a fixed set of strings to a gpointer. This can be used as -arbitrary extra members. Notice that each new field name -allocates a new quark, so it is probably best only to use -this for fields with fixed names. - - -The primary difference between object_data and arguments is that -the object defines two functions which set and get each type of argument. -The object just has a table to store its object data in: it does not -receive notice when data changes. - - -Objects are reference counted; this means that we maintain -a count of how many references (usually in the form of a pointer) -are being held to this object. -To indicate that you reference an object, call gtk_object_ref(). -The object will not be freed until everyone calls -gtk_object_unref(). - - -In order to reduce the chances of a memory leak, gtk+ defines -"floating objects". All objects created with gtk_object_new() -start out floating with a reference count of 1. -In order to reduce that initial reference count you should gtk_object_sink() -them, but usually the parent widget you add the child to will -sink the object. - -So, because gtk_widget_set_parent() sinks the object from -gtk_container_add(), there are no memory leaks in this code: - - - button = gtk_button_new_with_label("Hi Mom!"); - gtk_container_add(GTK_CONTAINER(window), button); - /* Button may not be used anymore since we don't retain a reference - * to it. */ - - -Likewise, the following code attaches the same adjustment to two -ranges: - - - adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0); - gtk_range_set_adjustment(range1, adjustment); - gtk_range_set_adjustment(range2, adjustment); - - -Note that we could put as many set_adjustments as we like: cleanup is easy -because they all retain a reference but only one sinks the initial reference -count. If it is possible for "range1" to stop retaining its reference -then we need to enclose the lines using "adjustment" with ref/unref -to guarantee the the object won't be deleted: - - - adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0); - gtk_object_ref(GTK_OBJECT(adjustment)); - gtk_range_set_adjustment(range1, adjustment); - gtk_range_set_adjustment(range1, another_adjustment); - /* With the initial reference, `adjustment' would have - * been deleted as `range1' lost its reference to it. */ - gtk_range_set_adjustment(range2, adjustment); - gtk_object_unref(GTK_OBJECT(adjustment)); - - - - -Be careful with reference counting: if two objects reference eachother -then they will always have at least reference count 1, even if -there are no other pointers to them. This means that they -will never be freed. More precisely, you must be certain that -your references never can form cycles. - - -If you find yourself forming cyclic references, perhaps you -can convert some of them to weak-references. -A weak-reference is one that holds a pointer to an object, -but doesn't increase the reference count. To insure -the object is valid when the referer tries to use it, -the referer registers a callback that will be invoked -after the object has been destroyed (but before its memory is actually -deallocated). This callback must prevent the weak-reference from -being used again. - - - -Brief Glossary - - - -argument - -A typed-variable identified by ObjectType::argument_name. It may be -readable, writable, both or none. For example, -"GtkButton::label" is a read/write string-valued argument. - - - - -constructed - - - - - -destroyed - - - - - -finalization - - - - - -floating - - - - - -object data - - - - - -reference count - - - - - -weak-reference - - - - - - - - - -GtkType, GtkArg, gtk-signals. - - - - -The object itself. You should never use these members directly- -instead you the accessing macros. - - -@klass: a pointer to the GtkObjectClass (or deriver) which contains -the methods defined by this object. -@flags: the state of the object: whether it has been constructed -or destroyed, for example. -@ref_count: a reference count. It is incremented when new -pointers to this object are made, and decremented when the -pointers are deleted. When the reference count -returns to 0, the object is deleted. By default, objects -have reference count 0 when created. -@object_data: - - - -Get the type of an object. - - -@obj: the object whose type we wish to get. - - - - -Get the array of signals defined for this object. - - -@obj: the object to fetch the signals from. - - - - -Get the number of signals defined by this object. - - -@obj: the object to query. - - - - -Tells about the state of the object. - - -@GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it -and is processing the shutdown callback. -@GTK_FLOATING: whether the object is orphaned. Objects that take -strong hold of an object may gtk_object_sink() it, after obtaining -there own references, if they believe they are nearly primary -ownership of the object. -GTK_CONNECTED: refers to whether are signals are connected to this -object. -@GTK_CONSTRUCTED: refers to whether the arguments for this object are -ready. - - - -Get the #GtkObjectFlags for an object without directly -accessing its members. - - -@obj: the object whose flags are returned. - - - - -Test whether a GtkObject has had gtk_object_destroyed() invoked on it. - - -@obj: the object to examine. - - - - -When an object is created, it has an initial reference count -of 1 and is floating. Sinking the object -refers to decrementing that original reference count. - - -@obj: the object to examine. - - - - -Test whether a GtkObject has had a signal connected to it. - - -@obj: the object to examine. - - - - -Test whether a GtkObject's arguments have been prepared. - - -@obj: the object to examine. - - - - -Turn on certain object flags. (Private) - - -@obj: the object to affect. -@flag: the flags to set. - - - - -Turn off certain object flags. (Private) - - -@obj: the object to affect. -@flag: the flags to unset. - - - - -Possible flags indicating how an argument should be treated. - - -@GTK_ARG_READABLE: the argument is readable. (i.e. can be queried) -@GTK_ARG_WRITABLE: the argument is writable. (i.e. settable) -@GTK_ARG_CONSTRUCT: the argument needs construction. -@GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will -be set once during object creation), but is otherwise cannot be -set. Hence this flag is not allowed with #GTK_ARG_WRITABLE, -and is redundant with #GTK_ARG_CONSTRUCT. -@GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for) -each child. Used by #GtkContainer. -@GTK_ARG_MASK: the bitwise-OR of all the flags. -@GTK_ARG_READWRITE: the argument is readable and writable. - - - -Define a signal-handler for a new signal on an already defined -object. - - -See the signal documentation for more general information. - - -@klass: the object class to define the signal for. -@name: the name of the signal. -@signal_flags: the default emission behavior for the signal. -See gtk_signal_new(). -@marshaller: a function that will take an array of GtkArgs -and invoke the appropriate handler with the normal calling -conventions. -@return_val: specify the return-value type for the signal -(or GTK_TYPE_NONE for no return-value). -@nparams: specify the number of parameters the signal -receives from the caller of gtk_signal_emit(). -@Varargs: list of nparams #GtkTypes to pass to the signal handlers. -@Returns: the signal id. (See #GtkSignals) - - - - -Define a signal-handler for a new signal on an already defined -object. - - -@klass: the object class to define the signal for. -@name: the name of the signal. -@signal_flags: the default emission behavior for the signal. -See gtk_signal_new(). -@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array -of arguments, and invokes the function using the appropriate -calling conventions. Usually just select a function -out of gtkmarshal.h. -@return_val: specify the return-value type for the signal (possibly -#GTK_TYPE_NONE). -@nparams: specify the number of parameters the signal -receives from the caller of gtk_signal_emit(). -@params: array of #GtkTypes the signal handlers for this signal -should have in their prototype (of length nparams). -@Returns: the signal id. (See #GtkSignals) - - - - -Construct an object given its arguments, enumerated in the call to the -function. - - -@type: the type identifying this object. Returned by gtk_type_unique() -although (for a properly-written object it should be accessible through -#GTK_TYPE_FOO.) -@first_arg_name: name of the first argument to set when constructing -the object. -@Varargs: the first argument's value, followed by any number of -name/argument-value pairs, terminated with NULL. -@Returns: the new GtkObject. - - - - -Construct an object with an array of arguments. - - -@object_type: the type of the object to create. -@n_args: the number of arguments to set. -@args: an array of n_args arguments (which are name and value pairs). -@Returns: the new GtkObject. - - - - -Mark an allocated object as constructed. -This is used for situations -that require precise control of the construction process. - - -This is done when gtk_object_default_construct() is inadequate. -In #GtkCList the need arises because #GtkCList does construction work that -must happen after its derivers. This work -cannot be done in an initializer function, so an alternate -constructor is mandatory. It calls gtk_object_constructed() to -indicate it has done its job, so that no other constructor will -be invoked. - - -Normally this function is just automatically run from -gtk_object_default_construct(). - - -@object: object which has been constructed. This is usually -done automatically by gtk_object_new() and gtk_object_newv(). - - - - -This function is called to construct arguments that haven't been initialized -but have the #GTK_ARG_CONSTRUCT flag set. - - -All number arguments are set to 0. All pointers and strings -are set to NULL. - - -Normally invoked by gtk_object_new() automatically; gtk_type_new() can -be used to bypass it. - - -@object: the object to initialize. - - - - -Decrement the initial count given to the object. -Additional invocations have no effect. - - -This is designed to free the user from worrying about -dereferencing an object that they have just created. -So long as the object is sunk at some point, the reference count -will be set properly. - - -furthermore it may be sunk multiple times. -Only the first time will actually dereference. - - -The basic outline is: when you create an object it is floating. -Setting its parent causes it to be sunk, however its parent -has obtained a reference, so its reference count is one. - - -@object: the object to sink. - - - - -Increase the reference count of the object. - - -@object: the object to reference. - - - - -Decrease the reference count of an object. When its reference -count drops to 0, the object is deleted. - - -If it was not already destroyed, it will be, with gtk_object_destroy(), -then weak links are notified, then the object-data is freed -and the memory for the object itself is freed using gtk_type_free(). - - -@object: the object to dereference. - - - - -Adds a weak reference callback to an object. - - -Weak references are a mechanism to safely keep a pointer to -an object without using the reference counting -mechansim. They use a callback function to receive -notice that the object is about to be freed (aka finalized). -This happens after the destroy -callback has been run. - - -@object: object to weakly reference. -@notify: callback to invoke before the object is freed. -@data: extra data to pass to #notify. - - - - -Removes a weak reference callback to an object. - - -@object: object stop weakly referencing. -@notify: callback to search for. -@data: data to search for. - - - - -Calls the object's shutdown handler. - - -The memory for the object itself won't be deleted until -its reference count drops to 0, though. -See gtk_object_unref(). - - -@object: the object to destroy. - - - - -Gets an array of argument values from an object. - - -@object: the object to get arguments from. -@n_args: the number of arguments to query. -@args: the arguments to fill in. - - - - -This function sets multiple arguments of an object. - - -It takes an object, then a list of name/value pairs -in a list, followed by NULL. - - - - -void set_box_properties(GtkBox* box) -{ - gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE, - "spacing", 8, - NULL); -} - - - - - -@object: the object whose arguments should be set. -@first_arg_name: the name of the first argument to set. -@Varargs: the value of the first argument, followed optionally -by more name/value pairs, followed by NULL. - - - -Set an array of arguments. - - -@object: the object whose arguments should be set. -@n_args: the number of arguments to set. -@args: the desired values, as an array of #GtkArgs (which contain -the names, types, and values of the arguments). - - - - -Get all the arguments that may be used for a given type. - - -In Java, this type of mechanism is called -introspection. It is used by applications -like Glade, that have to determine what can be done to an object -at run-time. - - -@class_type: the GtkType of the ObjectClass -(returned from GTK_OBJECT_CLASS(class)->type for example). -@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to -each argument. You must g_free() this if you request it. -@n_args: the number of arguments is returned in this field. -@Returns: an array of arguments, that you must deallocate with g_free(). - - - - -Each object carries around a table of associations from -strings to pointers. This function lets you set an association. - - -If the object already had an association with that name, -the old association will be destroyed. - - -@object: object containing the associations. -@key: name of the key. -@data: data to associate with that key. - - - - -Like gtk_object_set_data() except it adds notification -for when the association is destroyed, either by -gtk_object_remove_data() or when the object is destroyed. - - -@object: object containing the associations. -@key: name of the key. -@data: data to associate with that key. -@destroy: function to call when the association is destroyed. - - - - -Remove a specified datum from the object's data associations (the object_data). -Subsequent calls to gtk_object_get_data() will return NULL. - - -If you specified a destroy handler with gtk_object_set_data_full(), -it will be invoked. - - - -@object: the object maintaining the association. -@key: name of the key for that association. - - - - -Get a named field from the object's table of associations (the object_data). - - -@object: the object maintaining the associations. -@key: name of the key for that association. -@Returns: the data if found, or NULL if no such data exists. - - - - -Remove a specified datum from the object's data associations (the object_data), -without invoking the association's destroy handler. - - -Just like gtk_object_remove_data() except that any destroy handler -will be ignored. -Therefore this only affects data set using gtk_object_set_data_full(). - - -@object: the object maintaining the association. -@key: name of the key for that association. - - - - -For convenience, every object offers a generic user data -pointer. The function set it. - - -This function is equivalent to: - - - gtk_object_set_data(object, "user_data", data); - - - - -@object: the object whose user data should be set. -@data: the new value for the user data. - - - - -Get the object's user data pointer. - - -This is intended to be a pointer for your convenience in -writing applications. - - -@object: the object. -@Returns: the user data field for object. - - - - -Add an array of signals to a #GtkObjectClass. -Usually this is called when registering a new type of object. - - -@klass: the object class to append signals to. -@signals: the signals to append. -@nsignals: the number of signals being appended. - - - - -Add a new type of argument to an object class. -Usually this is called when registering a new type of object. - - -@arg_name: fully qualify object name, for example GtkObject::user_data. -@arg_type: type of the argument. -@arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is -settable or gettable, whether it is set when the object is constructed.) -@arg_id: an internal number, passed in from here to the "set_arg" and -"get_arg" handlers of the object. - - - - -Just like gtk_object_set_data() except that it takes -a #GQuark instead of a string, so it is slightly faster. - - -Use gtk_object_data_try_key() and gtk_object_data_force_id() -to get an id from a string. - - -@object: object containing the associations. -@data_id: quark of the key. -@data: data to associate with that key. - - - - -Just like gtk_object_set_data_full() except that it takes -a #GQuark instead of a string, so it is slightly faster. - - -Use gtk_object_data_try_key() and gtk_object_data_force_id() -to get an id from a string. - - -@object: object containing the associations. -@data_id: quark of the key. -@data: data to associate with that key. -@destroy: function to call when the association is destroyed. - - - - -Just like gtk_object_get_data() except that it takes -a #GQuark instead of a string, so it is slightly faster. - - -Use gtk_object_data_try_key() and gtk_object_data_force_id() -to get an id from a string. - - -@object: object containing the associations. -@data_id: quark of the key. -@Returns: the data if found, or NULL if no such data exists. - - - - -Just like gtk_object_remove_data() except that it takes -a #GQuark instead of a string, so it is slightly faster. - - -Remove a specified datum from the object's data associations. -Subsequent calls to gtk_object_get_data() will return NULL. - - -Use gtk_object_data_try_key() and gtk_object_data_force_id() -to get an id from a string. - - -@object: object containing the associations. -@data_id: quark of the key. - - - - -Just like gtk_object_remove_no_notify() except that it takes -a #GQuark instead of a string, so it is slightly faster. - - -Use gtk_object_data_try_key() and gtk_object_data_force_id() -to get an id from a string. - - -@object: object containing the associations. -@data_id: quark of the key. - - - - -Sees whether a certain quark exists. -Returns that quark if so. - - -Although this is currently the same as g_quark_try_string(), -it might someday be different, for example, if GQuarks -and object data are converted to separate mechanisms, -so it is good to use this macro. - - - - - - -Makes a quark from a string, possibly allocating a new quark. - - -Although this is currently the same as g_quark_from_string(), -it might someday be different, for example, if GQuarks -and object data are converted to separate mechanisms, -so it is good to use this macro. - - - - - - -Private function to set an argument and argument info to an object. - - -@object: the object whose argument should be set. -@arg: the argument. -@info: infomation about this type of argument in general. - - - - -Private function to get an argument and argument info from an object. - - -@object: the object whose argument should be retrieved. -@arg: the argument, for the name on input, the rest is filled on output. -@info: a #GtkArgInfo structure to optionally fill in. - - - - -Private: Gets an array of #GtkArgs from a va_list C structure. - - - -@object_type: the type of object to collect arguments for. -@arg_list_p: pointer to be filled in with a list of parsed arguments. -@info_list_p: optional pointer for a returned list #GtkArgInfos. -@first_arg_name: name of first argument. -@var_args: value of first argument, followed by more key/value pairs, -terminated by NULL. -@Returns: an error message, or NULL on success. -It is the caller's responsibility to call g_free() in the event of error. - - - - -Query information about an argument type. - - -@object_type: type of object to query about. -@arg_name: name of the argument. -@info_p: pointer to be filled in with a pointer to the GtkArgInfo. -@Returns: an error message, or NULL on success. -It is the caller's responsibility to call g_free() in the event of error. - - - - -Private: print debugging information while doing a gtk_object_ref() or -a gtk_object_unref(). - - -@object: object to reference or unreference. -@func: name of caller's function to print (used within macros). -@dummy: unused. -@line: line number (used within macros). -@do_ref: whether to reference or unreference. - - - - -Indicates that an object is being destroyed. - - -@object: the object which received the signal. - - - -A pointer for convenience when programming applications. - - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object. - - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object, so that the signal is always run -after other user handlers and the default handler. - - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object, so that the user data and objects -and swapped when the signal handler is invoked. - - -This is useful for handlers that are primarily notifying -other objects and could just invoke an already existing function -if the parameters were swapped. -See gtk_signal_connect_object() for more details. - - - - -Setting this with a GtkType of GTK_TYPE_SIGNAL connects -the signal to the object, so that the user data and objects -and swapped when the signal handler is invoked, -and so that the handler is invoked after all others. - - -See gtk_signal_connect_object_after() for more details. - - + +GtkObject + + +The base class of the Gtk type hierarchy. + + + +Description + +GtkObject is the root of the gtk+ type hierarchy. It serves +a similar roles as java's Object class. It is used +by the type-casting system to represent the base composite type. + + +Objects have arguments that are +name/typed-value pairs. +They may be readable or writable (or both or neither). +The special handlers in every object are responsible for +setting and getting these parameters. +If the handler for a given argument must +be called before the object may be used, be sure the +#GTK_ARG_CONSTRUCT or #GTK_ARG_CONSTRUCT_ONLY flags +are set; otherwise they are set only when the user does so. + + +Object also store a simpler association table, sometimes +called the object_data. This is just an efficient mapping from +a fixed set of strings to a gpointer. This can be used as +arbitrary extra members. Notice that each new field name +allocates a new quark, so it is probably best only to use +this for fields with fixed names. + + +The primary difference between object_data and arguments is that +the object defines two functions which set and get each type of argument. +The object just has a table to store its object data in: it does not +receive notice when data changes. + + +Objects are reference counted; this means that we maintain +a count of how many references (usually in the form of a pointer) +are being held to this object. +To indicate that you reference an object, call gtk_object_ref(). +The object will not be freed until everyone calls +gtk_object_unref(). + + +In order to reduce the chances of a memory leak, gtk+ defines +"floating objects". All objects created with gtk_object_new() +start out floating with a reference count of 1. +In order to reduce that initial reference count you should gtk_object_sink() +them, but usually the parent widget you add the child to will +sink the object. + +So, because gtk_widget_set_parent() sinks the object from +gtk_container_add(), there are no memory leaks in this code: + + + button = gtk_button_new_with_label("Hi Mom!"); + gtk_container_add(GTK_CONTAINER(window), button); + /* Button may not be used anymore since we don't retain a reference + * to it. */ + + +Likewise, the following code attaches the same adjustment to two +ranges: + + + adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0); + gtk_range_set_adjustment(range1, adjustment); + gtk_range_set_adjustment(range2, adjustment); + + +Note that we could put as many set_adjustments as we like: cleanup is easy +because they all retain a reference but only one sinks the initial reference +count. If it is possible for "range1" to stop retaining its reference +then we need to enclose the lines using "adjustment" with ref/unref +to guarantee the the object won't be deleted: + + + adjustment = (GtkAdjustment*) gtk_adjustment_new(0,10,0,0,0,0); + gtk_object_ref(GTK_OBJECT(adjustment)); + gtk_range_set_adjustment(range1, adjustment); + gtk_range_set_adjustment(range1, another_adjustment); + /* With the initial reference, `adjustment' would have + * been deleted as `range1' lost its reference to it. */ + gtk_range_set_adjustment(range2, adjustment); + gtk_object_unref(GTK_OBJECT(adjustment)); + + + + +Be careful with reference counting: if two objects reference eachother +then they will always have at least reference count 1, even if +there are no other pointers to them. This means that they +will never be freed. More precisely, you must be certain that +your references never can form cycles. + + +If you find yourself forming cyclic references, perhaps you +can convert some of them to weak-references. +A weak-reference is one that holds a pointer to an object, +but doesn't increase the reference count. To insure +the object is valid when the referer tries to use it, +the referer registers a callback that will be invoked +after the object has been destroyed (but before its memory is actually +deallocated). This callback must prevent the weak-reference from +being used again. + + + +Brief Glossary + + + +argument + +A typed-variable identified by ObjectType::argument_name. It may be +readable, writable, both or none. For example, +"GtkButton::label" is a read/write string-valued argument. + + + + +constructed + + + + + +destroyed + + + + + +finalization + + + + + +floating + + + + + +object data + + + + + +reference count + + + + + +weak-reference + + + + + + + + + +GtkType, GtkArg, gtk-signals. + + + + +The object itself. You should never use these members directly- +instead you the accessing macros. + + +@klass: a pointer to the GtkObjectClass (or deriver) which contains +the methods defined by this object. +@flags: the state of the object: whether it has been constructed +or destroyed, for example. +@ref_count: a reference count. It is incremented when new +pointers to this object are made, and decremented when the +pointers are deleted. When the reference count +returns to 0, the object is deleted. By default, objects +have reference count 0 when created. +@object_data: + + + +Get the type of an object. + + +@obj: the object whose type we wish to get. + + + + +Get the array of signals defined for this object. + + +@obj: the object to fetch the signals from. + + + + +Get the number of signals defined by this object. + + +@obj: the object to query. + + + + +Tells about the state of the object. + + +@GTK_DESTROYED: the GtkObject has had gtk_object_destroyed() invoked on it +and is processing the shutdown callback. +@GTK_FLOATING: whether the object is orphaned. Objects that take +strong hold of an object may gtk_object_sink() it, after obtaining +there own references, if they believe they are nearly primary +ownership of the object. +GTK_CONNECTED: refers to whether are signals are connected to this +object. +@GTK_CONSTRUCTED: refers to whether the arguments for this object are +ready. + + + +Get the #GtkObjectFlags for an object without directly +accessing its members. + + +@obj: the object whose flags are returned. + + + + +Test whether a GtkObject has had gtk_object_destroyed() invoked on it. + + +@obj: the object to examine. + + + + +When an object is created, it has an initial reference count +of 1 and is floating. Sinking the object +refers to decrementing that original reference count. + + +@obj: the object to examine. + + + + +Test whether a GtkObject has had a signal connected to it. + + +@obj: the object to examine. + + + + +Test whether a GtkObject's arguments have been prepared. + + +@obj: the object to examine. + + + + +Turn on certain object flags. (Private) + + +@obj: the object to affect. +@flag: the flags to set. + + + + +Turn off certain object flags. (Private) + + +@obj: the object to affect. +@flag: the flags to unset. + + + + +Possible flags indicating how an argument should be treated. + + +@GTK_ARG_READABLE: the argument is readable. (i.e. can be queried) +@GTK_ARG_WRITABLE: the argument is writable. (i.e. settable) +@GTK_ARG_CONSTRUCT: the argument needs construction. +@GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will +be set once during object creation), but is otherwise cannot be +set. Hence this flag is not allowed with #GTK_ARG_WRITABLE, +and is redundant with #GTK_ARG_CONSTRUCT. +@GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for) +each child. Used by #GtkContainer. +@GTK_ARG_MASK: the bitwise-OR of all the flags. +@GTK_ARG_READWRITE: the argument is readable and writable. + + + +Define a signal-handler for a new signal on an already defined +object. + + +See the signal documentation for more general information. + + +@klass: the object class to define the signal for. +@name: the name of the signal. +@signal_flags: the default emission behavior for the signal. +See gtk_signal_new(). +@marshaller: a function that will take an array of GtkArgs +and invoke the appropriate handler with the normal calling +conventions. +@return_val: specify the return-value type for the signal +(or GTK_TYPE_NONE for no return-value). +@nparams: specify the number of parameters the signal +receives from the caller of gtk_signal_emit(). +@Varargs: list of nparams #GtkTypes to pass to the signal handlers. +@Returns: the signal id. (See #GtkSignals) + + + + +Define a signal-handler for a new signal on an already defined +object. + + +@klass: the object class to define the signal for. +@name: the name of the signal. +@signal_flags: the default emission behavior for the signal. +See gtk_signal_new(). +@marshaller: takes a GtkObject, a #GtkSignalFunc, and an array +of arguments, and invokes the function using the appropriate +calling conventions. Usually just select a function +out of gtkmarshal.h. +@return_val: specify the return-value type for the signal (possibly +#GTK_TYPE_NONE). +@nparams: specify the number of parameters the signal +receives from the caller of gtk_signal_emit(). +@params: array of #GtkTypes the signal handlers for this signal +should have in their prototype (of length nparams). +@Returns: the signal id. (See #GtkSignals) + + + + +Construct an object given its arguments, enumerated in the call to the +function. + + +@type: the type identifying this object. Returned by gtk_type_unique() +although (for a properly-written object it should be accessible through +#GTK_TYPE_FOO.) +@first_arg_name: name of the first argument to set when constructing +the object. +@Varargs: the first argument's value, followed by any number of +name/argument-value pairs, terminated with NULL. +@Returns: the new GtkObject. + + + + +Construct an object with an array of arguments. + + +@object_type: the type of the object to create. +@n_args: the number of arguments to set. +@args: an array of n_args arguments (which are name and value pairs). +@Returns: the new GtkObject. + + + + +Mark an allocated object as constructed. +This is used for situations +that require precise control of the construction process. + + +This is done when gtk_object_default_construct() is inadequate. +In #GtkCList the need arises because #GtkCList does construction work that +must happen after its derivers. This work +cannot be done in an initializer function, so an alternate +constructor is mandatory. It calls gtk_object_constructed() to +indicate it has done its job, so that no other constructor will +be invoked. + + +Normally this function is just automatically run from +gtk_object_default_construct(). + + +@object: object which has been constructed. This is usually +done automatically by gtk_object_new() and gtk_object_newv(). + + + + +This function is called to construct arguments that haven't been initialized +but have the #GTK_ARG_CONSTRUCT flag set. + + +All number arguments are set to 0. All pointers and strings +are set to NULL. + + +Normally invoked by gtk_object_new() automatically; gtk_type_new() can +be used to bypass it. + + +@object: the object to initialize. + + + + +Decrement the initial count given to the object. +Additional invocations have no effect. + + +This is designed to free the user from worrying about +dereferencing an object that they have just created. +So long as the object is sunk at some point, the reference count +will be set properly. + + +furthermore it may be sunk multiple times. +Only the first time will actually dereference. + + +The basic outline is: when you create an object it is floating. +Setting its parent causes it to be sunk, however its parent +has obtained a reference, so its reference count is one. + + +@object: the object to sink. + + + + +Increase the reference count of the object. + + +@object: the object to reference. + + + + +Decrease the reference count of an object. When its reference +count drops to 0, the object is deleted. + + +If it was not already destroyed, it will be, with gtk_object_destroy(), +then weak links are notified, then the object-data is freed +and the memory for the object itself is freed using gtk_type_free(). + + +@object: the object to dereference. + + + + +Adds a weak reference callback to an object. + + +Weak references are a mechanism to safely keep a pointer to +an object without using the reference counting +mechansim. They use a callback function to receive +notice that the object is about to be freed (aka finalized). +This happens after the destroy +callback has been run. + + +@object: object to weakly reference. +@notify: callback to invoke before the object is freed. +@data: extra data to pass to #notify. + + + + +Removes a weak reference callback to an object. + + +@object: object stop weakly referencing. +@notify: callback to search for. +@data: data to search for. + + + + +Calls the object's shutdown handler. + + +The memory for the object itself won't be deleted until +its reference count drops to 0, though. +See gtk_object_unref(). + + +@object: the object to destroy. + + + + +Gets an array of argument values from an object. + + +@object: the object to get arguments from. +@n_args: the number of arguments to query. +@args: the arguments to fill in. + + + + +This function sets multiple arguments of an object. + + +It takes an object, then a list of name/value pairs +in a list, followed by NULL. + + + + +void set_box_properties(GtkBox* box) +{ + gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE, + "spacing", 8, + NULL); +} + + + + + +@object: the object whose arguments should be set. +@first_arg_name: the name of the first argument to set. +@Varargs: the value of the first argument, followed optionally +by more name/value pairs, followed by NULL. + + + +Set an array of arguments. + + +@object: the object whose arguments should be set. +@n_args: the number of arguments to set. +@args: the desired values, as an array of #GtkArgs (which contain +the names, types, and values of the arguments). + + + + +Get all the arguments that may be used for a given type. + + +In Java, this type of mechanism is called +introspection. It is used by applications +like Glade, that have to determine what can be done to an object +at run-time. + + +@class_type: the GtkType of the ObjectClass +(returned from GTK_OBJECT_CLASS(class)->type for example). +@arg_flags: if non-NULL, obtains the #GtkArgFlags that apply to +each argument. You must g_free() this if you request it. +@n_args: the number of arguments is returned in this field. +@Returns: an array of arguments, that you must deallocate with g_free(). + + + + +Each object carries around a table of associations from +strings to pointers. This function lets you set an association. + + +If the object already had an association with that name, +the old association will be destroyed. + + +@object: object containing the associations. +@key: name of the key. +@data: data to associate with that key. + + + + +Like gtk_object_set_data() except it adds notification +for when the association is destroyed, either by +gtk_object_remove_data() or when the object is destroyed. + + +@object: object containing the associations. +@key: name of the key. +@data: data to associate with that key. +@destroy: function to call when the association is destroyed. + + + + +Remove a specified datum from the object's data associations (the object_data). +Subsequent calls to gtk_object_get_data() will return NULL. + + +If you specified a destroy handler with gtk_object_set_data_full(), +it will be invoked. + + + +@object: the object maintaining the association. +@key: name of the key for that association. + + + + +Get a named field from the object's table of associations (the object_data). + + +@object: the object maintaining the associations. +@key: name of the key for that association. +@Returns: the data if found, or NULL if no such data exists. + + + + +Remove a specified datum from the object's data associations (the object_data), +without invoking the association's destroy handler. + + +Just like gtk_object_remove_data() except that any destroy handler +will be ignored. +Therefore this only affects data set using gtk_object_set_data_full(). + + +@object: the object maintaining the association. +@key: name of the key for that association. + + + + +For convenience, every object offers a generic user data +pointer. The function set it. + + +This function is equivalent to: + + + gtk_object_set_data(object, "user_data", data); + + + + +@object: the object whose user data should be set. +@data: the new value for the user data. + + + + +Get the object's user data pointer. + + +This is intended to be a pointer for your convenience in +writing applications. + + +@object: the object. +@Returns: the user data field for object. + + + + +Add an array of signals to a #GtkObjectClass. +Usually this is called when registering a new type of object. + + +@klass: the object class to append signals to. +@signals: the signals to append. +@nsignals: the number of signals being appended. + + + + +Add a new type of argument to an object class. +Usually this is called when registering a new type of object. + + +@arg_name: fully qualify object name, for example GtkObject::user_data. +@arg_type: type of the argument. +@arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is +settable or gettable, whether it is set when the object is constructed.) +@arg_id: an internal number, passed in from here to the "set_arg" and +"get_arg" handlers of the object. + + + + +Just like gtk_object_set_data() except that it takes +a #GQuark instead of a string, so it is slightly faster. + + +Use gtk_object_data_try_key() and gtk_object_data_force_id() +to get an id from a string. + + +@object: object containing the associations. +@data_id: quark of the key. +@data: data to associate with that key. + + + + +Just like gtk_object_set_data_full() except that it takes +a #GQuark instead of a string, so it is slightly faster. + + +Use gtk_object_data_try_key() and gtk_object_data_force_id() +to get an id from a string. + + +@object: object containing the associations. +@data_id: quark of the key. +@data: data to associate with that key. +@destroy: function to call when the association is destroyed. + + + + +Just like gtk_object_get_data() except that it takes +a #GQuark instead of a string, so it is slightly faster. + + +Use gtk_object_data_try_key() and gtk_object_data_force_id() +to get an id from a string. + + +@object: object containing the associations. +@data_id: quark of the key. +@Returns: the data if found, or NULL if no such data exists. + + + + +Just like gtk_object_remove_data() except that it takes +a #GQuark instead of a string, so it is slightly faster. + + +Remove a specified datum from the object's data associations. +Subsequent calls to gtk_object_get_data() will return NULL. + + +Use gtk_object_data_try_key() and gtk_object_data_force_id() +to get an id from a string. + + +@object: object containing the associations. +@data_id: quark of the key. + + + + +Just like gtk_object_remove_no_notify() except that it takes +a #GQuark instead of a string, so it is slightly faster. + + +Use gtk_object_data_try_key() and gtk_object_data_force_id() +to get an id from a string. + + +@object: object containing the associations. +@data_id: quark of the key. + + + + +Sees whether a certain quark exists. +Returns that quark if so. + + +Although this is currently the same as g_quark_try_string(), +it might someday be different, for example, if GQuarks +and object data are converted to separate mechanisms, +so it is good to use this macro. + + + + + + +Makes a quark from a string, possibly allocating a new quark. + + +Although this is currently the same as g_quark_from_string(), +it might someday be different, for example, if GQuarks +and object data are converted to separate mechanisms, +so it is good to use this macro. + + + + + + +Private function to set an argument and argument info to an object. + + +@object: the object whose argument should be set. +@arg: the argument. +@info: infomation about this type of argument in general. + + + + +Private function to get an argument and argument info from an object. + + +@object: the object whose argument should be retrieved. +@arg: the argument, for the name on input, the rest is filled on output. +@info: a #GtkArgInfo structure to optionally fill in. + + + + +Private: Gets an array of #GtkArgs from a va_list C structure. + + +@object_type: the type of object to collect arguments for. +@arg_list_p: pointer to be filled in with a list of parsed arguments. +@info_list_p: optional pointer for a returned list #GtkArgInfos. +@first_arg_name: name of first argument. +@var_args: value of first argument, followed by more key/value pairs, +terminated by NULL. +@Returns: an error message, or NULL on success. +It is the caller's responsibility to call g_free() in the event of error. + + + + +Query information about an argument type. + + +@object_type: type of object to query about. +@arg_name: name of the argument. +@info_p: pointer to be filled in with a pointer to the GtkArgInfo. +@Returns: an error message, or NULL on success. +It is the caller's responsibility to call g_free() in the event of error. + + + + +Private: print debugging information while doing a gtk_object_ref() or +a gtk_object_unref(). + + +@object: object to reference or unreference. +@func: name of caller's function to print (used within macros). +@dummy: unused. +@line: line number (used within macros). +@do_ref: whether to reference or unreference. + + + + +Indicates that an object is being destroyed. + + +@object: the object which received the signal. + + + +A pointer for convenience when programming applications. + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object. + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object, so that the signal is always run +after other user handlers and the default handler. + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object, so that the user data and objects +and swapped when the signal handler is invoked. + + +This is useful for handlers that are primarily notifying +other objects and could just invoke an already existing function +if the parameters were swapped. +See gtk_signal_connect_object() for more details. + + + + +Setting this with a GtkType of GTK_TYPE_SIGNAL connects +the signal to the object, so that the user data and objects +and swapped when the signal handler is invoked, +and so that the handler is invoked after all others. + + +See gtk_signal_connect_object_after() for more details. + + diff --git a/docs/reference/gtk/tmpl/gtkprogress.sgml b/docs/reference/gtk/tmpl/gtkprogress.sgml index e722243e45..c883498459 100644 --- a/docs/reference/gtk/tmpl/gtkprogress.sgml +++ b/docs/reference/gtk/tmpl/gtkprogress.sgml @@ -52,18 +52,22 @@ current progress. The string can contain the following substitution characters: %%v - the current progress value. + %%l - the lower bound for the progress value. + %%u - the upper bound for the progress value. + %%p - the current progress percentage. + diff --git a/docs/reference/gtk/tmpl/gtksignal.sgml b/docs/reference/gtk/tmpl/gtksignal.sgml index de67e84bf9..aab2ec0c46 100644 --- a/docs/reference/gtk/tmpl/gtksignal.sgml +++ b/docs/reference/gtk/tmpl/gtksignal.sgml @@ -5,146 +5,146 @@ Signals Object methods and callbacks. - -What are signals? - -Signals are a way to get notification when something happens -and to customize object behavior according to the -user's needs. -Every signal is uniquely identified by a name, -"class_name::signal_name", where signal_name might be something like -"clicked" and class_name might be "GtkButton". Note that some other class -may also define a "clicked" callback, so long as it doesn't derive from -#GtkButton. - - -When they are created, they are also assigned a unique positive integer, -the signal id (1 is the first signal id- 0 is used to flag an error). -Each is also tied to an array of types that describes -the prototype of the function pointer(s) (handlers) you may -connect to the signal. Finally, every signal has -a default handler that is given by a function pointer -in its class structure: it is run by default whenever the -signal is emitted. (It is possible that a signal will -be emitted and a user-defined handler will prevent the default handler -from being run.) - - -Signals are used by everyone, but they are only -created on a per class basis-- so you should call -call gtk_signal_new() unless you are writing -a new #GtkObject type. However, if you want to make a new signal -for an existing type, you may use gtk_object_class_user_signal_new() -to create a signal that doesn't correspond to a class's builtin -methods. - - - -How are signals used? - -There are two basic actions in the signal handling game. -If you want notification of an event, you must connect -a function pointer and a data pointer to that signal; the data pointer -will be passed as the last argument to the function (so long as you -are using the default marshalling functions). -You will receive a connection id, a unique positive integer -corresponding to that attachment. - - -Functions that want to notify the user of certain actions, -emit signals. - - - -Basic Terminology - - - -signal -A class method, e.g. GtkButton::clicked. -More precisely it is a unique class-branch/signal-name pair. -This means you may not define a signal handler for a class which -derives from GtkButton that is called clicked, -but it is okay to share signals names if they are separate in -the class tree. - - - - -default handler -The object's internal method which is invoked -when the signal is emitted. - - - - -user-defined handler -A function pointer and data connected -to a signal (for a particular object). -There are really two types: those which are connected -normally, and those which are connected by one -of the connect_after functions. The connect_after handlers -are always run after the default handler. -Many toolkits refer to these as callbacks. - - - - -emission -the whole process of emitting a signal, -including the invocation of all -the different handler types mentioned above. - - - - -signal id -The unique positive (nonzero) integer -used to identify a signal. It can be used instead of -a name to many functions for a slight performance -improvement. - - - - -connection id -The unique positive (nonzero) integer -used to identify the connection of a user-defined handler -to a signal. Notice that it is allowed to connect the -same function-pointer/user-data pair twice, so -there is no guarantee that a function-pointer/user-data -maps to a unique connection id. - - - - - - - -A brief note on how they work. - -The functions responsible for translating an array of #GtkArgs -to your C compiler's normal semantics are called Marshallers. -They are identified by -gtk_marshal_return_value__parameter_list() -for example a C function returning a gboolean and taking a gint -can be invoked by using gtk_marshal_BOOL__INT(). -Not all possibly combinations of return/params are available, -of course, so if you are writing a #GtkObject with parameters -you might have to write a marshaller. - + +What are signals? + +Signals are a way to get notification when something happens +and to customize object behavior according to the +user's needs. +Every signal is uniquely identified by a name, +"class_name::signal_name", where signal_name might be something like +"clicked" and class_name might be "GtkButton". Note that some other class +may also define a "clicked" callback, so long as it doesn't derive from +#GtkButton. + + +When they are created, they are also assigned a unique positive integer, +the signal id (1 is the first signal id- 0 is used to flag an error). +Each is also tied to an array of types that describes +the prototype of the function pointer(s) (handlers) you may +connect to the signal. Finally, every signal has +a default handler that is given by a function pointer +in its class structure: it is run by default whenever the +signal is emitted. (It is possible that a signal will +be emitted and a user-defined handler will prevent the default handler +from being run.) + + +Signals are used by everyone, but they are only +created on a per class basis-- so you should call +call gtk_signal_new() unless you are writing +a new #GtkObject type. However, if you want to make a new signal +for an existing type, you may use gtk_object_class_user_signal_new() +to create a signal that doesn't correspond to a class's builtin +methods. + + + +How are signals used? + +There are two basic actions in the signal handling game. +If you want notification of an event, you must connect +a function pointer and a data pointer to that signal; the data pointer +will be passed as the last argument to the function (so long as you +are using the default marshalling functions). +You will receive a connection id, a unique positive integer +corresponding to that attachment. + + +Functions that want to notify the user of certain actions, +emit signals. + + + +Basic Terminology + + + +signal +A class method, e.g. GtkButton::clicked. +More precisely it is a unique class-branch/signal-name pair. +This means you may not define a signal handler for a class which +derives from GtkButton that is called clicked, +but it is okay to share signals names if they are separate in +the class tree. + + + + +default handler +The object's internal method which is invoked +when the signal is emitted. + + + + +user-defined handler +A function pointer and data connected +to a signal (for a particular object). +There are really two types: those which are connected +normally, and those which are connected by one +of the connect_after functions. The connect_after handlers +are always run after the default handler. +Many toolkits refer to these as callbacks. + + + + +emission +the whole process of emitting a signal, +including the invocation of all +the different handler types mentioned above. + + + + +signal id +The unique positive (nonzero) integer +used to identify a signal. It can be used instead of +a name to many functions for a slight performance +improvement. + + + + +connection id +The unique positive (nonzero) integer +used to identify the connection of a user-defined handler +to a signal. Notice that it is allowed to connect the +same function-pointer/user-data pair twice, so +there is no guarantee that a function-pointer/user-data +maps to a unique connection id. + + + + + + + +A brief note on how they work. + +The functions responsible for translating an array of #GtkArgs +to your C compiler's normal semantics are called Marshallers. +They are identified by +gtk_marshal_return_value__parameter_list() +for example a C function returning a gboolean and taking a gint +can be invoked by using gtk_marshal_BOOL__INT(). +Not all possibly combinations of return/params are available, +of course, so if you are writing a #GtkObject with parameters +you might have to write a marshaller. + - - - - -#GtkObject -The base class for things which emit signals. - - - + + + + +#GtkObject +The base class for things which emit signals. + + + @@ -157,12 +157,12 @@ you might have to write a marshaller. - -This is currently a hack left in for a scheme wrapper library. -It may be removed. - - -Don't use it. + +This is currently a hack left in for a scheme wrapper library. +It may be removed. + + +Don't use it. @object: The object which emits the signal. @@ -170,56 +170,56 @@ Don't use it. @nparams: The number of parameters to the function. @args: The actual values of the arguments. @arg_types: The types of the arguments. -@return_type: The type of the return value from the function +@return_type: The type of the return value from the function or #GTK_TYPE_NONE for no return value. - -A function which you can use to clean up when the -signal handler is destroyed. - - -For example, if your handler requires a few variables -that you made into a struct and allocated (using g_new() -or something), then you will probably want to free -it as soon as the hook is destroyed. This will -allow you to do that. (For this in particular -it is convenient to pass g_free() as a #GtkSignalDestroy -function). - - -@data: The user data associated with the hook that is being + +A function which you can use to clean up when the +signal handler is destroyed. + + +For example, if your handler requires a few variables +that you made into a struct and allocated (using g_new() +or something), then you will probably want to free +it as soon as the hook is destroyed. This will +allow you to do that. (For this in particular +it is convenient to pass g_free() as a #GtkSignalDestroy +function). + + +@data: The user data associated with the hook that is being destroyed. - -A simple function pointer to get invoked when the -signal is emitted. This allows you tie a hook to the signal type, -so that it will trap all emissions of that signal, from any object. - - -You may not attach these to signals created with the -#GTK_RUN_NO_HOOKS flag. + +A simple function pointer to get invoked when the +signal is emitted. This allows you tie a hook to the signal type, +so that it will trap all emissions of that signal, from any object. + + +You may not attach these to signals created with the +#GTK_RUN_NO_HOOKS flag. @object: the object which emits the signal. @signal_id: the unique integer identify the signal type. -@n_params: the number of parameters to the function, +@n_params: the number of parameters to the function, not including return value. -@params: the parameters to the function. A pointer to +@params: the parameters to the function. A pointer to the return value is passed as a last element. @data: the user data associated with the hook. -@Returns: whether it wished to be removed. If it returns +@Returns: whether it wished to be removed. If it returns TRUE, the signal hook is disconnected (and destroyed). - -This structure contains all the information about a particular -signal: its name, the type it affects, the signature of the handlers, -and its unique identifying integer. + +This structure contains all the information about a particular +signal: its name, the type it affects, the signature of the handlers, +and its unique identifying integer. @object_type: @@ -232,71 +232,71 @@ and its unique identifying integer. @params: - -These configure the signal's emission. They control -whether the signal can be emitted recursively on an object -and -whether to run the default method before or after the user-defined handlers. - - - - - -GTK_RUN_FIRST -Run the default handler before the connected user-defined -handlers. - - - - -GTK_RUN_LAST -Run the default handler after the connected -user-defined handlers. -(Handlers registered as "after" always run after the default handler though) - - - - -GTK_RUN_BOTH -Run the default handler twice, -once before the user-defined handlers, -and -once after. - - - - -GTK_RUN_NO_RECURSE -Whether to prevent a handler or hook -from reemitting the signal from within itself. -Attempts to -emit the signal while it is running will result in the signal -emission being restarted once it is done with the current processing. - -You must be -careful to avoid having two handlers endlessly reemitting signals, -gtk_signal_n_emissions() can be helpful. - - - - -GTK_RUN_ACTION -The signal is an action you can -invoke without any particular setup or cleanup. -The signal is treated no differently, but some -other code can determine if the signal is appropriate to -delegate to user control. For example, key binding sets -only allow bindings of ACTION signals to keystrokes. - - - - -GTK_RUN_NO_HOOKS -This prevents the connection of emission hooks -to the signal. - - - + +These configure the signal's emission. They control +whether the signal can be emitted recursively on an object +and +whether to run the default method before or after the user-defined handlers. + + + + + +GTK_RUN_FIRST +Run the default handler before the connected user-defined +handlers. + + + + +GTK_RUN_LAST +Run the default handler after the connected +user-defined handlers. +(Handlers registered as "after" always run after the default handler though) + + + + +GTK_RUN_BOTH +Run the default handler twice, +once before the user-defined handlers, +and +once after. + + + + +GTK_RUN_NO_RECURSE +Whether to prevent a handler or hook +from reemitting the signal from within itself. +Attempts to +emit the signal while it is running will result in the signal +emission being restarted once it is done with the current processing. + +You must be +careful to avoid having two handlers endlessly reemitting signals, +gtk_signal_n_emissions() can be helpful. + + + + +GTK_RUN_ACTION +The signal is an action you can +invoke without any particular setup or cleanup. +The signal is treated no differently, but some +other code can determine if the signal is appropriate to +delegate to user control. For example, key binding sets +only allow bindings of ACTION signals to keystrokes. + + + + +GTK_RUN_NO_HOOKS +This prevents the connection of emission hooks +to the signal. + + + @GTK_RUN_FIRST: @@ -314,27 +314,27 @@ to the signal. - -Create a new signal type. (This is usually done in the -class initializer.) + +Create a new signal type. (This is usually done in the +class initializer.) @name: the event name for the signal, e.g. "clicked". -@signal_flags: a combination of GTK_RUN flags -specifying detail of when the default handler is to be invoked. -You should at least specify #GTK_RUN_FIRST +@signal_flags: a combination of GTK_RUN flags +specifying detail of when the default handler is to be invoked. +You should at least specify #GTK_RUN_FIRST or #GTK_RUN_LAST. -@object_type: the type of object this signal pertains to. +@object_type: the type of object this signal pertains to. It will also pertain to derivers of this type automatically. -@function_offset: How many bytes the function pointer is in -the class structure for this type. Used to invoke a class +@function_offset: How many bytes the function pointer is in +the class structure for this type. Used to invoke a class method generically. -@marshaller: the function to translate between an array -of GtkArgs and the native calling convention. Usually they -are identified just by the type of arguments they take: -for example, gtk_marshal_BOOL__STRING() describes a marshaller +@marshaller: the function to translate between an array +of GtkArgs and the native calling convention. Usually they +are identified just by the type of arguments they take: +for example, gtk_marshal_BOOL__STRING() describes a marshaller which takes a string and returns a boolean value. -@return_val: the type of return value, or GTK_TYPE_NONE for a signal +@return_val: the type of return value, or GTK_TYPE_NONE for a signal without a return value. @nparams: the number of parameter the handlers may take. @Varargs: a list of GTK_TYPE_*, one for each parameter. @@ -342,37 +342,37 @@ without a return value. - -Create a new signal type. (This is usually done in a -class initializer.) - - -This function take the types as an array, instead of a list -following the arguments. Otherwise the same as gtk_signal_new(). + +Create a new signal type. (This is usually done in a +class initializer.) + + +This function take the types as an array, instead of a list +following the arguments. Otherwise the same as gtk_signal_new(). @name: the name of the signal to create. @signal_flags: see gtk_signal_new(). @object_type: the type of GtkObject to associate the signal with. -@function_offset: how many bytes the function pointer is in +@function_offset: how many bytes the function pointer is in the class structure for this type. @marshaller: -@return_val: the type of the return value, or GTK_TYPE_NONE if +@return_val: the type of the return value, or GTK_TYPE_NONE if you don't want a return value. @nparams: the number of parameters to the user-defined handlers. -@params: an array of GtkTypes, describing the prototype to +@params: an array of GtkTypes, describing the prototype to the callbacks. @Returns: the signal id. - -Given the name of the signal and the type of object it connects -to, get the signal's identifying integer. Emitting the signal -by number is somewhat faster than using the name each time. - - -It also tries the ancestors of the given type. + +Given the name of the signal and the type of object it connects +to, get the signal's identifying integer. Emitting the signal +by number is somewhat faster than using the name each time. + + +It also tries the ancestors of the given type. @name: the signal's name, e.g. clicked. @@ -381,11 +381,11 @@ It also tries the ancestors of the given type. - -Given the signal's identifier, find its name. - - -Two different signals may have the same name, if they have differing types. + +Given the signal's identifier, find its name. + + +Two different signals may have the same name, if they have differing types. @signal_id: the signal's identifying number. @@ -393,110 +393,111 @@ Two different signals may have the same name, if they have differing types. - -Emit a signal. This causes the default handler and user-defined -handlers to be run. - - -Here is what gtk_signal_emit() does: - - -1. Calls the default handler and the user-connected handlers. -The default handler will be called first if -GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set. - - -2. Calls all handlers connected with the "after" flag set. + +Emit a signal. This causes the default handler and user-defined +handlers to be run. + + +Here is what gtk_signal_emit() does: + + +1. Calls the default handler and the user-connected handlers. +The default handler will be called first if +GTK_RUN_FIRST is set, and last if GTK_RUN_LAST is set. + + +2. Calls all handlers connected with the "after" flag set. @object: the object that emits the signal. @signal_id: the signal identifier. -@Varargs: the parameters to the function, followed +@Varargs: the parameters to the function, followed by a pointer to the return type, if any. - -Emit a signal. This causes the default handler and user-connected -handlers to be run. + +Emit a signal. This causes the default handler and user-connected +handlers to be run. @object: the object that emits the signal. @name: the name of the signal. -@Varargs: the parameters to the function, followed +@Varargs: the parameters to the function, followed by a pointer to the return type, if any. - -Emit a signal. This causes the default handler and user-connected -handlers to be run. This differs from gtk_signal_emit() by taking -an array of GtkArgs instead of using C's varargs mechanism. + +Emit a signal. This causes the default handler and user-connected +handlers to be run. This differs from gtk_signal_emit() by taking +an array of GtkArgs instead of using C's varargs mechanism. @object: the object to emit the signal to. @signal_id: the signal identifier. -@params: an array of GtkArgs, one for each parameter, +@params: an array of GtkArgs, one for each parameter, followed by one which is a pointer to the return type. - -Emit a signal by name. This causes the default handler and user-connected -handlers to be run. This differs from gtk_signal_emit() by taking -an array of GtkArgs instead of using C's varargs mechanism. + +Emit a signal by name. This causes the default handler and user-connected +handlers to be run. This differs from gtk_signal_emit() by taking +an array of GtkArgs instead of using C's varargs mechanism. @object: the object to emit the signal to. @name: the name of the signal. -@params: an array of GtkArgs, one for each parameter, +@params: an array of GtkArgs, one for each parameter, followed by one which is a pointer to the return type. - -Find out the recursion depth of emissions for a particular type -of signal and object. (So it will -always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified) -This is a way to avoid recursion: you can see if -you are currently running in that signal handler and emit it only -if you are. - -Another way to look at it is that this number increases -by one when #gtk_signal_emit(), et al, are called, -and decreases by one when #gtk_signal_emit() returns. + +Find out the recursion depth of emissions for a particular type +of signal and object. (So it will +always return 0 or 1 if #GTK_RUN_NO_RECURSE is specified) +This is a way to avoid recursion: you can see if +you are currently running in that signal handler and emit it only +if you are. + +Another way to look at it is that this number increases +by one when #gtk_signal_emit(), et al, are called, +and decreases by one when #gtk_signal_emit() returns. @object: the object with the signal handler. @signal_id: the signal id. -@Returns: the recursion depth of emissions of this signal for this +@Returns: the recursion depth of emissions of this signal for this object. - -Find out the recursion depth of emissions for a particular type -of signal and object. Just like gtk_signal_n_emissions() -except it will lookup the signal id for you. + +Find out the recursion depth of emissions for a particular type +of signal and object. Just like gtk_signal_n_emissions() +except it will lookup the signal id for you. @object: the object with the signal handler. @name: the signal name. -@Returns: the recursion depth of emissions of this signal for this +@Returns: the recursion depth of emissions of this signal for this object. - -This function aborts a signal's current emission. - - -It will prevent the default method from running, -if the signal was #GTK_RUN_LAST and you connected -normally (i.e. without the "after" flag). - -It will print a warning if used on a signal which -isn't being emitted. + +This function aborts a signal's current emission. + + +It will prevent the default method from running, +if the signal was #GTK_RUN_LAST and you connected +normally (i.e. without the "after" flag). + + +It will print a warning if used on a signal which +isn't being emitted. @object: the object whose signal handlers you wish to stop. @@ -504,12 +505,12 @@ isn't being emitted. - -This function aborts a signal's current emission. - -It is just like -gtk_signal_emit_stop() -except it will lookup the signal id for you. + +This function aborts a signal's current emission. + +It is just like +gtk_signal_emit_stop() +except it will lookup the signal id for you. @object: the object whose signal handlers you wish to stop. @@ -517,44 +518,45 @@ except it will lookup the signal id for you. - -Attach a function pointer and user data to a signal for -a particular object. - - -The GtkSignalFunction takes a GtkObject as its first parameter. -It will be the same object as the one you're connecting -the hook to. The func_data will be passed as the last parameter -to the hook. - - -All else being equal, signal handlers are invoked in the order -connected (see gtk_signal_emit() for the other details of -which order things are called in). - - -Here is how one passes an integer as user data, -for when you just want to specify a constant int -as parameter to your function: - - -static void button_clicked_int(GtkButton* button, gpointer func_data) -{ - g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data)); -} - -/* By calling this function, you will make the g_print above - * execute, printing the number passed as `to_print'. */ -static void attach_print_signal(GtkButton* button, gint to_print) -{ - gtk_signal_connect(GTK_OBJECT(button), "clicked", - GTK_SIGNAL_FUNC(button_clicked_int), - GINT_TO_POINTER(to_print)); -} - + +Attach a function pointer and user data to a signal for +a particular object. + + +The GtkSignalFunction takes a GtkObject as its first parameter. +It will be the same object as the one you're connecting +the hook to. The func_data will be passed as the last parameter +to the hook. + + +All else being equal, signal handlers are invoked in the order +connected (see gtk_signal_emit() for the other details of +which order things are called in). + + +Here is how one passes an integer as user data, +for when you just want to specify a constant int +as parameter to your function: + + + +static void button_clicked_int(GtkButton* button, gpointer func_data) +{ + g_print("button pressed: %d\n", GPOINTER_TO_INT(func_data)); +} + +/* By calling this function, you will make the g_print above + * execute, printing the number passed as `to_print'. */ +static void attach_print_signal(GtkButton* button, gint to_print) +{ + gtk_signal_connect(GTK_OBJECT(button), "clicked", + GTK_SIGNAL_FUNC(button_clicked_int), + GINT_TO_POINTER(to_print)); +} + -@object: the object associated with the signal, e.g. if a button +@object: the object associated with the signal, e.g. if a button is getting pressed, this is that button. @name: name of the signal. @func: function pointer to attach to the signal. @@ -563,9 +565,9 @@ is getting pressed, this is that button. - -Attach a function pointer and user data to a signal -so that this handler will be called after the other handlers. + +Attach a function pointer and user data to a signal +so that this handler will be called after the other handlers. @object: the object associated with the signal. @@ -576,41 +578,41 @@ so that this handler will be called after the other handlers. - -This function is for registering a callback that will -call another object's callback. That is, -instead of passing the object which is responsible -for the event as the first parameter of the callback, -it is switched with the user data (so the object which emits -the signal will be the last parameter, which is where the -user data usually is). - - -This is useful for passing a standard function in as a callback. -For example, if you wanted a button's press to gtk_widget_show() -some widget, you could write: - - - -gtk_signal_connect_object(button, "clicked", gtk_widget_show, window); - + +This function is for registering a callback that will +call another object's callback. That is, +instead of passing the object which is responsible +for the event as the first parameter of the callback, +it is switched with the user data (so the object which emits +the signal will be the last parameter, which is where the +user data usually is). + + +This is useful for passing a standard function in as a callback. +For example, if you wanted a button's press to gtk_widget_show() +some widget, you could write: + + + +gtk_signal_connect_object(button, "clicked", gtk_widget_show, window); + @object: the object which emits the signal. @name: the name of the signal. @func: the function to callback. -@slot_object: the object to pass as the first parameter to func. -(Though it pretends to take an object, you can +@slot_object: the object to pass as the first parameter to func. +(Though it pretends to take an object, you can really pass any gpointer as the #slot_object .) @Returns: the connection id. - -Attach a signal hook to a signal, passing in an alternate -object as the first parameter, and guaranteeing -that the default handler and all normal -handlers are called first. + +Attach a signal hook to a signal, passing in an alternate +object as the first parameter, and guaranteeing +that the default handler and all normal +handlers are called first. @object: the object associated with the signal. @@ -621,92 +623,92 @@ handlers are called first. - -Attach a function pointer and user data to a signal with -more control. + +Attach a function pointer and user data to a signal with +more control. -@object: the object which emits the signal. For example, a button +@object: the object which emits the signal. For example, a button in the button press signal. @name: the name of the signal. @func: function pointer to attach to the signal. -@marshal: the function marshal, see the gtkmarshall documentation for -more details, but briefly: the marshaller is a function which takes -the #GtkObject which emits the signal, the user data, the number of the -arguments, and the array of arguments. It is responsible for -calling the function in the appropriate calling convention. -gtk_signal_default_marshaller is usually fine. -(This shows up, for example, when worrying about matching +@marshal: the function marshal, see the gtkmarshall documentation for +more details, but briefly: the marshaller is a function which takes +the #GtkObject which emits the signal, the user data, the number of the +arguments, and the array of arguments. It is responsible for +calling the function in the appropriate calling convention. +gtk_signal_default_marshaller is usually fine. +(This shows up, for example, when worrying about matching c++ or other languages' calling conventions.) @data: the user data associated with the function. -@destroy_func: function to call when this particular hook is +@destroy_func: function to call when this particular hook is disconnected. -@object_signal: whether this is an object signal-- basically an "object -signal" is one that wants its user_data and object fields switched, -which is useful for calling functions which operate on another +@object_signal: whether this is an object signal-- basically an "object +signal" is one that wants its user_data and object fields switched, +which is useful for calling functions which operate on another object primarily. -@after: whether to invoke the user-defined handler after the signal, or to let -the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST +@after: whether to invoke the user-defined handler after the signal, or to let +the signal's default behavior preside (i.e. depending on #GTK_RUN_FIRST and #GTK_RUN_LAST). @Returns: the connection id. - -Attach a function pointer and another GtkObject to a signal. - - -This function takes an object whose "destroy" signal -should be trapped. -That way, you don't have to clean up the -signal handler when you destroy the object. -It is a little less efficient though. - - -(Instead you may call gtk_signal_disconnect_by_data(), if you want -to explicitly delete all attachments to this object. This -is perhaps not recommended since it could be confused -with an integer masquerading as a pointer (through GINT_AS_POINTER).) + +Attach a function pointer and another GtkObject to a signal. + + +This function takes an object whose "destroy" signal +should be trapped. +That way, you don't have to clean up the +signal handler when you destroy the object. +It is a little less efficient though. + + +(Instead you may call gtk_signal_disconnect_by_data(), if you want +to explicitly delete all attachments to this object. This +is perhaps not recommended since it could be confused +with an integer masquerading as a pointer (through GINT_AS_POINTER).) @object: the object that emits the signal. @signal: @func: function pointer to attach to the signal. @func_data: pointer to pass to func. -@alive_object: object whose death should cause the handler connection +@alive_object: object whose death should cause the handler connection to be destroyed. @name: name of the signal. - -These signal connectors are for signals which refer to objects, -so they must not be called after the object is deleted. - - -Unlike gtk_signal_connect_while_alive(), -this swaps the object and user data, making it suitable for -use with functions which primarily operate on the user data. - - -This function acts just like gtk_signal_connect_object() except -it traps the "destroy" signal to prevent you from having to -clean up the handler. + +These signal connectors are for signals which refer to objects, +so they must not be called after the object is deleted. + + +Unlike gtk_signal_connect_while_alive(), +this swaps the object and user data, making it suitable for +use with functions which primarily operate on the user data. + + +This function acts just like gtk_signal_connect_object() except +it traps the "destroy" signal to prevent you from having to +clean up the handler. @object: the object associated with the signal. @signal: @func: function pointer to attach to the signal. -@alive_object: the user data, which must be an object, whose destruction +@alive_object: the user data, which must be an object, whose destruction should signal the removal of this signal. @name: name of the signal. - -Destroy a user-defined handler connection. + +Destroy a user-defined handler connection. @object: the object which the handler pertains to. @@ -714,9 +716,9 @@ Destroy a user-defined handler connection. - -Destroy all connections for a particular object, with -the given function-pointer and user-data. + +Destroy all connections for a particular object, with +the given function-pointer and user-data. @object: the object which emits the signal. @@ -725,9 +727,9 @@ the given function-pointer and user-data. - -Destroy all connections for a particular object, with -the given user-data. + +Destroy all connections for a particular object, with +the given user-data. @object: the object which emits the signal. @@ -735,10 +737,10 @@ the given user-data. - -Prevent an user-defined handler from being invoked. All other -signal processing will go on as normal, but this particular -handler will ignore it. + +Prevent an user-defined handler from being invoked. All other +signal processing will go on as normal, but this particular +handler will ignore it. @object: the object which emits the signal to block. @@ -746,10 +748,10 @@ handler will ignore it. - -Prevent a user-defined handler from being invoked, by reference to -the user-defined handler's function pointer and user data. (It may result in -multiple hooks being blocked, if you've called connect multiple times.) + +Prevent a user-defined handler from being invoked, by reference to +the user-defined handler's function pointer and user data. (It may result in +multiple hooks being blocked, if you've called connect multiple times.) @object: the object which emits the signal to block. @@ -758,8 +760,8 @@ multiple hooks being blocked, if you've called connect multiple times.) - -Prevent all user-defined handlers with a certain user data from being invoked. + +Prevent all user-defined handlers with a certain user data from being invoked. @object: the object which emits the signal we want to block. @@ -767,23 +769,23 @@ Prevent all user-defined handlers with a certain user data from being invoked. - -Undo a block, by connection id. Note that undoing a block doesn't -necessarily make the hook callable, because if you block a -hook twice, you must unblock it twice. + +Undo a block, by connection id. Note that undoing a block doesn't +necessarily make the hook callable, because if you block a +hook twice, you must unblock it twice. @object: the object which emits the signal we want to unblock. -@handler_id: the emission handler identifier, as returned by +@handler_id: the emission handler identifier, as returned by gtk_signal_connect(), etc. - -Undo a block, by function pointer and data. -Note that undoing a block doesn't -necessarily make the hook callable, because if you block a -hook twice, you must unblock it twice. + +Undo a block, by function pointer and data. +Note that undoing a block doesn't +necessarily make the hook callable, because if you block a +hook twice, you must unblock it twice. @object: the object which emits the signal we want to unblock. @@ -792,9 +794,9 @@ hook twice, you must unblock it twice. - -Undo block(s), to all signals for a particular object -with a particular user-data pointer + +Undo block(s), to all signals for a particular object +with a particular user-data pointer @object: the object which emits the signal we want to unblock. @@ -802,32 +804,32 @@ with a particular user-data pointer - -Returns a connection id corresponding to a given signal id and object. - - -One example of when you might use this is when the arguments -to the signal are difficult to compute. A class implementor -may opt to not emit the signal if no one is attached anyway, -thus saving the cost of building the arguments. + +Returns a connection id corresponding to a given signal id and object. + + +One example of when you might use this is when the arguments +to the signal are difficult to compute. A class implementor +may opt to not emit the signal if no one is attached anyway, +thus saving the cost of building the arguments. @object: the object to search for the desired user-defined handler. @signal_id: the number of the signal to search for. -@may_be_blocked: whether it is acceptable to return a blocked +@may_be_blocked: whether it is acceptable to return a blocked handler. @Returns: the connection id, if a connection was found. 0 otherwise. - -Returns a connection id corresponding to a given signal id, object, function -pointer and user data. + +Returns a connection id corresponding to a given signal id, object, function +pointer and user data. @object: the object to search for the desired handler. @signal_id: the number of the signal to search for. -@may_be_blocked: whether it is acceptable to return a blocked +@may_be_blocked: whether it is acceptable to return a blocked handler. @func: the function pointer to search for. @data: the user data to search for. @@ -835,89 +837,89 @@ handler. - -Returns whether a connection id is valid (and optionally not blocked). + +Returns whether a connection id is valid (and optionally not blocked). @object: the object to search for the desired handler. @handler_id: the connection id. -@may_be_blocked: whether it is acceptable to return a blocked +@may_be_blocked: whether it is acceptable to return a blocked handler. -@Returns: TRUE if the signal exists and wasn't blocked, +@Returns: TRUE if the signal exists and wasn't blocked, unless #may_be_blocked was specified. FALSE otherwise. - -Destroy all the signal handlers connected to an object. -This is done automatically when the object is destroyed. - - -This function is labeled private. + +Destroy all the signal handlers connected to an object. +This is done automatically when the object is destroyed. + + +This function is labeled private. @object: the object whose signal handlers should be destroyed. - -These set default functions to call when the user didn't -supply a function when connecting. (These are rarely -used, and probably only for language bindings) - - -By default, there are no such functions. + +These set default functions to call when the user didn't +supply a function when connecting. (These are rarely +used, and probably only for language bindings) + + +By default, there are no such functions. -@marshal_func: the function to invoke on every handlers for which there +@marshal_func: the function to invoke on every handlers for which there isn't a function pointer. May be NULL. -@destroy_func: the function to invoke when each hook is destroyed. +@destroy_func: the function to invoke when each hook is destroyed. May be NULL. - -Obtain information about a signal. + +Obtain information about a signal. @signal_id: the signal type identifier. -@Returns: a pointer to a GtkSignalQuery structure -which contains all the information, or NULL. +@Returns: a pointer to a GtkSignalQuery structure +which contains all the information, or NULL. The pointer is allocated just for you: you must g_free() it. - -Add an emission hook for a type of signal, for any object. + +Add an emission hook for a type of signal, for any object. @signal_id: the type of signal to hook for. @hook_func: the function to invoke to handle the emission hook. @data: the user data passed in to hook_func. -@Returns: the id (that you may pass as a parameter +@Returns: the id (that you may pass as a parameter to gtk_signal_remove_emission_hook()). - -Add an emission hook for a type of signal, for any object. -(with control of what happens when the hook is -destroyed). + +Add an emission hook for a type of signal, for any object. +(with control of what happens when the hook is +destroyed). @signal_id: the type of signal add the hook for. @hook_func: the function to invoke to handle the hook. @data: the user data passed in to hook_func. -@destroy: a function to invoke when the hook is destroyed, -to clean up any allocation done just for this +@destroy: a function to invoke when the hook is destroyed, +to clean up any allocation done just for this signal handler. -@Returns: the id (that you may pass as a parameter +@Returns: the id (that you may pass as a parameter to gtk_signal_remove_emission_hook()). - -Delete an emission hook. (see gtk_signal_add_emission_hook()) + +Delete an emission hook. (see gtk_signal_add_emission_hook()) @signal_id: the id of the signal type. -- 2.30.2